Node / meshtastic / Meshtastic-Android / files / specs / 006-kmp-project-structure / research.md

Displaying Rendered • View raw • Download

Decision: Use T383838androidLibrary {} as the canonical DSL accessor for the KMP Android target.

Rationale: The T383838androidLibrary {} accessor is the documented API in the KMP recommended structure guide and the KMP-App-Template. While T383838android {} inside T383838kotlin {} is a transitional alias that still works (used by kotlinconf-app), T383838androidLibrary {} is the forward-looking name that clearly distinguishes between:

• T383838kotlin { androidLibrary {} } — KMP module Android target (new plugin)

• T383838android {} — top-level Android extension (legacy T383838com.android.library or T383838com.android.application)

Using T383838androidLibrary {} eliminates ambiguity and signals the project uses the recommended patterns.

Alternatives considered:

• Keep T383838android {} inside T383838kotlin {} (works but ambiguous, transitional)

• Use programmatic API only in convention plugins (already done for compileSdk/minSdk; per-module overrides still need DSL)

Decision: Convention plugin (T383838configureKotlinMultiplatform()) handles:

• T383838compileSdk ✅ (already done)

• T383838minSdk ✅ (already done, default from config.properties)

• T383838namespace auto-derivation ✅ (already done when null)

• T383838androidResources.enable = false as default ← NEW (absorb into convention)

Module T383838build.gradle.kts handles only overrides:

• T383838namespace when it differs from auto-derived (e.g., T383838feature.wifiprovision vs T383838feature.wifi-provision)

• T383838minSdk override (only T383838core:proto with minSdk 21)

• T383838androidResources { enable = true; resourcePrefix = "..." } (only T383838core:resources)

• T383838withHostTest {} / T383838withDeviceTest {} (per-module opt-in)

Rationale: The convention plugin already handles compileSdk/minSdk/namespace via T383838KotlinMultiplatformAndroidLibraryTarget. Adding T383838androidResources.enable = false as the convention default eliminates the most common per-module boilerplate (23 of 27 modules set this).

Alternatives considered:

• Move all config to convention plugin, including withHostTest (rejected: test opt-in should be explicit per-module)

• Keep all config in module files (rejected: adds repetitive boilerplate across 27 modules)

Decision: The T383838configureKotlinMultiplatform() function in T383838KotlinAndroid.kt is already well-structured. One enhancement needed:

1. Add T383838androidResources.enable = false as default in the T383838pluginManager.withPlugin block alongside compileSdk/minSdk/namespace. This eliminates the most common boilerplate line across 23 modules.

The T383838KmpLibraryConventionPlugin.kt, T383838KmpFeatureConventionPlugin.kt, and T383838KmpJvmAndroidConventionPlugin.kt do NOT need changes — they compose correctly and delegate to T383838configureKotlinMultiplatform().

Rationale: The convention plugin chain is already correct:

• T383838KmpLibraryConventionPlugin applies T383838com.android.kotlin.multiplatform.library (correct plugin)

• T383838configureKotlinMultiplatform() uses T383838KotlinMultiplatformAndroidLibraryTarget API (correct API)

• T383838isDesktopOnly guard is properly implemented

• The only gap is that individual modules repeat T383838androidResources.enable = false

Alternatives considered:

• Rewrite convention plugins to use DSL instead of programmatic API (rejected: programmatic API via T383838KotlinMultiplatformAndroidLibraryTarget is cleaner in convention plugins and already works)

• Add T383838withHostTest {} to convention by default (rejected: not all modules need host tests, and some configure T383838isIncludeAndroidResources = true)

Decision: Categorize all 27 modules into migration tiers based on complexity.

These modules only set namespace and disable resources. After convention absorbs T383838androidResources.enable = false, these only need namespace (or nothing if auto-derived matches).

These add T383838withHostTest {} opt-in. The T383838androidLibrary {} block will keep withHostTest.

• T383838core:api — T383838meshtastic.android.library, AIDL, publishing

• T383838core:barcode — T383838meshtastic.android.library, Android-only

• T383838feature:widget — T383838meshtastic.android.library, Glance widgets

• T383838app/ — T383838com.android.application

• T383838desktop/ — JVM only

• T383838screenshot-tests/ — Android test module

Decision: No changes needed to DESKTOP_ONLY mode. The migration is purely a DSL rename.

Rationale:

• T383838isDesktopOnly guard in T383838KmpLibraryConventionPlugin skips T383838com.android.kotlin.multiplatform.library plugin application entirely

• T383838configureKotlinMultiplatform() creates inert placeholder T383838androidMain source set in desktop-only mode

• The T383838kotlin { androidLibrary {} } DSL accessor in module build files is provided by the plugin — when the plugin isn't applied (desktop-only), the accessor doesn't exist

• The existing T383838android {} accessor inside T383838kotlin {} works the same way — so the rename from T383838android {} to T383838androidLibrary {} has identical desktop-only behavior

Key validation: After migration, T383838DESKTOP_ONLY=true ./gradlew :desktop:packageUberJarForCurrentOS must succeed.

Decision: Remove redundant T383838jvm() from module build files as a cleanup during migration — the convention plugin handles it. Calling T383838jvm() twice is a no-op (Kotlin Gradle Plugin is idempotent for target declarations), so removing it is safe. This reduces boilerplate and makes convention ownership clear.

Alternatives considered: Keep T383838jvm() in all modules for explicitness (rejected: inconsistent since some modules already omit it, and convention plugins are the source of truth).

Decision: Rely on convention plugin auto-derivation for most modules; only override where the derived name doesn't match.

Finding: Only T383838feature:wifi-provision has a namespace mismatch — the module path contains a hyphen which auto-derives as T383838org.meshtastic.feature.wifi.provision (with dot separator) but the module currently uses T383838org.meshtastic.feature.wifiprovision (no dot). This module MUST explicitly set T383838namespace in its T383838androidLibrary {} block.

All other modules that currently set T383838namespace explicitly match the auto-derived value and can safely rely on the convention plugin's auto-derivation. However, being explicit about namespace provides documentation value and prevents silent changes if the module is moved.

Decision: Remove explicit T383838namespace from modules where it matches auto-derivation. Keep it only for T383838feature:wifi-provision. This reduces boilerplate and delegates ownership to the convention plugin.